NewMod 1.9.2 - Copyright (C) 2000 Mark "WarZone" Smeltzer
---------------------------------------------------------

Disclaimer:
-----------

By using this product you agree to exempt, without reservation, the authors and owners of 
this production or components thereof from any responsibility for liability, damage caused, 
or loss, directly or indirectly, by this software, including but not limited to, any 
interruptions of service, loss of business, or any other consequential damages resulting 
from the use of or operation of this product or components thereof. No warranties are made, 
expressed or implied, regarding the usage, functionality, or implied operability of this 
product. All elements are available solely on an "as-is" basis. Usage is subject to the 
user's own risk. 

Requirements:
-------------

You MUST have the Q3A source installed in the root directory of your hard drive. For
example, C:\quake3\source, or D:\quake3\source, etc. This file CANNOT be buried in your hard
drive.

Installation:
-------------

Extract this archive to the root (base, main, umm, top level) directory on the drive of your
choice.. ie. extract it to either C:\, D:\, E:\, F:\, etc. DO NOT bury the archive into your
directory structure as it will not end up in the same directory as the Quake3 source.

Likewise, you should have already have the quake3 source could in c:\quake3, d:\quake3\, ...
etc. This archive should contain the following files:

- newmod.exe
- compilemod.exe
- copygame.dat
- copycgame.dat
- copyui.dat
- copyproject.dat
- buildgame.dat
- buildcgame.dat
- buildui.dat
- compile.bat
- NewMod ReadMe.txt
- NewMod source.zip

If you do not have all of these files, then you do not have a valid copy of NewMod.

The Short Of It:
----------------

This program exists to facilitate programmers with an EASY method of creating a new
batch of source files that will be instantly compilable -- and will even compile the QVM
files into the proper directory!

The program requires 3 command line parameters:
- mod's name (modname)
- directory to put the mod's code (modpath)
- path to Q3A (Q3path)

Here's the syntax NewMod expects:
newmod <modname> <modpath> <Q3path> <options>

Here's what a typical call to NewMod looks like:
newmod mynewmod c:\mynewmod c:\"program files"\"quake iii arena"

Or, maybe something like this:
newmod newmod d:\mods\newmod d:\games\quake3

After NewMod has created your new mod's files, you can compile your mod _from any directory_
by typing "compile_<modname>" in the console, where <modname> is the name of your mod. For
example, typing:
compile_ctf

Which will attempt to compile the CTF mod.

The Long Of It:
---------------

The mod's name and source directory are up to you, but you MUST supply NewMod with the
corrent path to Q3A. An easy way to do this is open up "My Computer" and go to the directory
where you installed Q3A. Find the Quake3 executable and right click on it, create shortcut, 
right click on the new shortcut, click properties, the field "Target" should already be 
highlighted, deselect it and rehighlight ONLY the path portion (not the Quake3.exe part), 
right click on the highlighted text and click copy.

Now that you've got the path to Q3A in the clipboard buffer, click the start menu, click
run, type "command.com" and hit enter. Assuming you've already installed the source code, 
and NewMod, type "C:" and hit enter (change this to the drive where your copy of the Q3 
source lives), type "cd quake3\source", then type "newmod <modname> <modpath> ", click on 
the MS-DOS icon in the upper left corner of the window, click on Edit, and then click Paste. 
Now that you've got the command line ready to roll, hit the enter key and NewMod will begin 
a process copying and creating the neccessary files to build you new mod. :)

Included with NewMod is a batch file named "compile.bat" which is copied to your mod's 
source directory. By double clicking on this file all three QVM files (game, cgame, and ui)
will be built and placed into your mod's directory in your main Q3A directory. Once that's 
done, you can double click the "playit.bat" file to automatically load Q3A with your mod. 
Cool, huh?

After NewMod has created your new mod's files, you can compile your mod _from any directory_
by typing "compile_<modname>" in the console, where <modname> is the name of your mod. For
example, typing:
compile_ctf

Which will attempt to compile the CTF mod. Unlike the compile.bat file which must be run in
your mod's source directory, a compile_modname.bat file can be run from ANY directory.


The <options>:
--------------

The following options are valid options that will affect the behavior of NewMod:
* overwrite - this option will allow NewMod to overwrite an existing mod.
    If a mod of the same name is found, you will be prompted whether to overwrite it or not.
* localedit - this option will cause NewMod to automatically edit the g_local.h file,
    changing the GAMEVERSION #define to the "modname" you selected. If you don't let NewMod
    do this, you're going to have to do it anyway in order to run your mod.. so you might as
    well.
* publicedit - this option will cause NewMod to automatically edit the bg_public.h file,
    changing the GAME_VERSION #define to the "modname" you selected. The actual value
    assigned to GAME_VERSION is "modname-1", Q3A's source has GAME_VERSION defined as
    "baseq3-1", so I'm just following id's example here. You should ONLY change this #define
    if your mod makes use of a custom cgame or ui module. Changing this value will break
    compatability with the standard cgame and ui modules.

Creating Backups:
-----------------

NewMod's "backup" command can be used to perform a complete backup of your source code.
At the command prompt, change to your mod's source directory. Then the following
command will create a backup copy of your code:
  newmod backup

Once that command is complete, you'll have a complete copy of your source code in
backups\<nextnumber>.. ok, let me explain the number part. NewMod will create
a small file in the backups directory the first time you make a backup, and the
source will be put in backups\1. The second backup you make is put in backups\2,
then backup\3, then backups\4, etc. you get the idea. The counter information is stored
in "backups\counter.dat"


Restoring from a backup:
------------------------

To restore from a backup operation, simply go to you mod's source directory with 
"My Computer" or Windows Explorer. Then double click on the "backups" directory.
Double click on the backup that you want to restore from. Then click on Edit->Select All, 
and then Edit->Cut in the window's menu.

Then go back to your mod's source folder and click Edit->Paste. The source code from the
backup will overwrite your current set of code, so be very careful when doing a full
restoration... it could turn into total destruction!

A much better way to restore "bad sections" of code (code you've hopelessly mangled)
is to copy and paste the individual files you need out of the backup directories.


Modifying the DAT files:
------------------------

There are seven DAT files included with NewMod, these files are simple text based scripts
that tell NewMod how to create a copy of the current source code. So, what does that mean?
It means that even if new releases of the source code introduce new files, NewMod can
incorporate those files simply by adding them into the DAT scripts. It also means that
NewMod can be used as a very powerful source code backup system. By simply adding the new
files that your mod needs to the DAT scripts, you can create an entire source backup with
one command line, and best of all, the source copy is immediately playable. This makes it
very easy to load up an older version of you mod to see what you've changed. Not to mention
disaster recovery -- the worst situation you can ever be in is accidentally deleting a 
section of your own code and then saving the file! Disaster recovery is no sweat as long as
you make regular backups.

Here's a list of each DAT file and what it does:

  name                    function
  --------------------------------------------------------------------------------------
  copygame.dat            files from the "game" directory that need to be copied
  copycgame.dat           files from the "cgame" directory that need to be copied
  copyui.dat              files from the "game" directory that need to be copied
  copyproject.dat         files from the current directory that need to be copied

  buildgame.dat           files that need to be included in the game.q3asm compiler script
  buildcgame.dat          files that need to be included in the cgame.q3asm compiler script
  buildui.dat             files that need to be included in the ui.q3asm compiler script

So, if you add a new source file called "g_newweapons.c" to the game module, you have 
to add "g_newweapons.c" to the end of the copygame.dat and buildgame.dat files in order to
use NewMod to make backups.

Or, supposing id software adds a new file called "newstuff.c" to the cgame module, you have
to add "newstuff.c" to the end of the copycgame.dat and buildcgame.dat files in order to
use NewMod create new mod projects.

FAQ's:
------

Q:  I don't like using DOS, is there any other way to use this program?
A1: To use the NewMod program, you currently *must* use DOS. I will eventually at a simple
    GUI to the program so it can be accessed by simply double clicking on it.
A2: Once you have run NewMod and created a new set of source code for your mod, you can
    easily compile it by clicking Start->Run and in the "Open" field type "compile_" 
    followed by the name of your mod. Ex. "compile_ctf"

Q:  How can I use NewMod to make source code backups?
A:  At the command prompt, change to your mod's source directory. Then the following
    command will create a backup copy of your code:
      newmod backup

Q:  I'm getting an error about the source code being invalid what gives?
A:  NewMod MUST be run from a directory containing a valid copy of the source code. NewMod
    checks to make sure that a game, cgame, and ui directory exists. If all three are not
    present, then you will see this error. This happens because NewMod is working directory
    based -- meaning it will spend its life in \quake3\bin_nt, but it can have access to
    source code anywhere on your hard drive.


Q:  When I run compile.bat I get lots of "file not found" errors...
A:  Reinstall the Q3 source to \quake3\! The path \quake3\bin_nt must exist in the root
    directory of your hard drive.

Have a question? Send it to warzone@planetquake.com!

Contact Info:
-------------

If you need to contact me for some reason, I can be reached via email at:
  warzone@planetquake.com


Version History:
----------------

1.9.2 - Added the "backup" command
      - Added multilevel path creation -- NewMod can now create a modpath like 
        c:\mods\mark\january\hmmm\s\g\j\i\s\q232 if you really want it too.
      - "play it.bat" files renamed to "playit.bat"
      - fixed "bug" in getexecutablepath() relating to Win2k issues. This is a Win2k bug IMO
1.8.0 - Added the CompileMod component
        - used to call a mod's compile.bat file from anywhere on your hard drive
      - Now creates a \quake3\bin_nt\compile_modname.bat file which calls compilemod
        with the parameters for your mod.
      - Source code clean up, and reorganization.
1.5.3 - Added 3 new command line options:
        - overwrite
        - localedit
        - publicedit
      - Source code converted to ANSI C (removed the C++ stuff)
      - File size cut in half!
      - newmod.exe now stored in \quake3\bin_nt so it can be run from any directory
        (if you have a newmod.exe file in \quake3\source, you must delete it to use the new
        version)
1.0.0 - Initial Release

--------------------------------------------------
NewMod. Copyright (C) 2000 Mark "WarZone" Smeltzer
